Notification Flow Distribution

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

This document describes the notification flow distribution system that orchestrates multi-channel delivery of notifications to users via Telegram and Web Push. It explains the routing architecture, batching strategy, channel prioritization, delivery guarantees, error handling, retry logic, user preferences, and queueing mechanisms. It also documents integration patterns between the notification service and channel handlers, including message transformation and delivery confirmation.

The notification system spans several modules:

• Service orchestration: NotificationService, NotificationRunner

• Channel implementations: TelegramService, WebPushService

• Infrastructure: DatabaseService, TelegramClient, Configuration

• Servers: BotServer, SchedulerServer

• CLI entry points and scheduling: main.py

Diagram sources

• main.py

• notification_runner.py

• notification_service.py

• telegram_service.py

• web_push_service.py

• database_service.py

• telegram_client.py

• bot_server.py

• scheduler_server.py

• config.py

Section sources

• main.py

• ARCHITECTURE.md

• NotificationService: Central router that dispatches messages to enabled channels and manages batched delivery of unsent notices.

• TelegramService: Implements channel-specific logic for Telegram, including message formatting, long-message chunking, rate limiting, and user broadcasting.

• WebPushService: Implements channel-specific logic for Web Push, including VAPID authentication, subscription management hooks, and broadcast delivery.

• NotificationRunner: CLI-driven orchestrator that wires channels and triggers send operations based on flags.

• DatabaseService: Provides persistent storage for notices, user management, and delivery state tracking.

• TelegramClient: Low-level Telegram API client with retry/backoff and rate-limit handling.

• Configuration: Centralized settings management for tokens, keys, and runtime flags.

Section sources

• notification_service.py

• telegram_service.py

• web_push_service.py

• notification_runner.py

• database_service.py

• telegram_client.py

• config.py

The notification flow is a multi-stage pipeline:

1. Data ingestion populates notices in the database with a pending state.

2. The scheduler or CLI triggers sending of unsent notices.

3. NotificationService batches notices and routes them to enabled channels.

4. Channel handlers transform messages and deliver to users.

5. Delivery state is persisted to mark notices as sent.

Diagram sources

• main.py

• notification_runner.py

• notification_service.py

• database_service.py

• telegram_service.py

• web_push_service.py

• telegram_client.py

NotificationService#

• Responsibilities:

  • Aggregates multiple channels and routes messages accordingly.

  • Batches unsent notices and marks them sent upon successful delivery.

  • Provides channel-specific send and broadcast helpers.

• Key behaviors:

  • Channel selection by name for targeted delivery.

  • Iterative broadcast across enabled channels with per-channel error handling.

  • Delivery guarantees: marks as sent if at least one channel succeeds; otherwise increments failures.

Diagram sources

• notification_service.py

Section sources

• notification_service.py

• notification_service.py

• notification_service.py

TelegramService#

• Responsibilities:

  • Implements channel contract for Telegram.

  • Formats messages (Markdown/HTML) and handles long messages by chunking.

  • Broadcasts to all active users with rate limiting.

  • Retries with fallback to plain text when formatting fails.

• Key behaviors:

  • Long message splitting with newline-aware chunking.

  • Markdown-to-Telegram conversion and HTML conversion.

  • Per-user delivery with small delays to avoid rate limits.

  • Fallback retry without parse_mode on initial failure.

Diagram sources

• telegram_service.py

• telegram_client.py

Section sources

• telegram_service.py

• telegram_service.py

• telegram_service.py

• telegram_service.py

• telegram_client.py

WebPushService#

• Responsibilities:

  • Implements channel contract for Web Push.

  • Manages VAPID authentication and subscription-based delivery.

  • Broadcasts to all users with push subscriptions.

  • Gracefully degrades when pywebpush is unavailable.

• Key behaviors:

  • Checks availability of VAPID keys and pywebpush library.

  • Broadcasts per subscription with truncation and payload formatting.

  • Handles expired subscriptions by removing them from DB (placeholder).

  • Returns success counts and error details.

Diagram sources

• web_push_service.py

Section sources

• web_push_service.py

• web_push_service.py

• web_push_service.py

• web_push_service.py

NotificationRunner#

• Responsibilities:

  • CLI-driven orchestration for sending unsent notices.

  • Dependency injection for testability and modularity.

  • Conditional enabling of channels based on flags and availability.

• Key behaviors:

  • Creates channel instances only when enabled.

  • Builds NotificationService with selected channels.

  • Executes send_unsent_notices and returns results.

Diagram sources

• notification_runner.py

Section sources

• notification_runner.py

• notification_runner.py

DatabaseService Integration#

• Responsibilities:

  • Stores notices with pending state and tracks delivery per channel.

  • Retrieves unsent notices and marks them sent upon successful delivery.

  • Provides user lists for channel broadcasts.

• Key behaviors:

  • get_unsent_notices() returns notices not yet sent to Telegram.

  • mark_as_sent() sets sent flag and timestamps.

  • get_active_users() supplies recipients for broadcasts.

Diagram sources

• database_service.py

• notification_service.py

Section sources

• database_service.py

• database_service.py

Servers and Scheduling#

• BotServer: Telegram bot with command handlers and DI support; integrates NotificationService for administrative commands.

• SchedulerServer: Automated job runner that executes the same update-and-send sequence on a schedule.

Diagram sources

• scheduler_server.py

• bot_server.py

Section sources

• bot_server.py

• scheduler_server.py

• Coupling:

  • NotificationService depends on channel implementations via a simple interface (channel_name property and broadcast_to_all_users/send_message).

  • Channels depend on DatabaseService for user lists and on TelegramClient for Telegram API calls.

  • NotificationRunner injects channels and DB into NotificationService.

• Cohesion:

  • Each service has a single responsibility: orchestration, channel delivery, or persistence.

• External dependencies:

  • Telegram Bot API (via TelegramClient).

  • Optional Web Push library (pywebpush) with graceful degradation.

  • MongoDB via DatabaseService.

Diagram sources

• notification_service.py

• telegram_service.py

• web_push_service.py

• telegram_client.py

• database_service.py

• notification_runner.py

• bot_server.py

• scheduler_server.py

Section sources

• notification_service.py

• telegram_service.py

• web_push_service.py

• notification_runner.py

• Batching:

  • NotificationService iterates unsent notices and broadcasts to enabled channels; batching occurs at the notice level.

• Rate limiting:

  • TelegramService applies small delays between user sends and long message chunking to avoid rate limits.

  • TelegramClient implements exponential backoff and respects Retry-After headers.

• Concurrency:

  • Current implementation performs sequential broadcasts per notice; parallelization could improve throughput but risks rate limits and DB contention.

• Memory and CPU:

  • Long message splitting and markdown conversions are linear in message length; consider streaming or chunking strategies for very large content.

[No sources needed since this section provides general guidance]

• Telegram delivery failures:

  • Verify bot token and chat ID are configured; TelegramClient validates presence before sending.

  • Check rate limits; TelegramClient handles 429 with Retry-After.

  • Long messages are split; if formatting fails, TelegramService retries without parse_mode.

• Web Push delivery failures:

  • Ensure VAPID keys are configured; WebPushService checks availability and logs warnings when disabled.

  • Expired subscriptions are handled by attempting removal; implement DB-specific removal logic if needed.

• Database connectivity:

  • DatabaseService methods return empty results or errors when collections are uninitialized; confirm connection string and collection initialization.

• CLI usage:

  • Use send command with appropriate flags (–telegram, --web, --both) and optional --fetch to include data updates.

Section sources

• telegram_client.py

• telegram_service.py

• web_push_service.py

• web_push_service.py

• database_service.py

• main.py

The notification flow distribution system provides a robust, extensible architecture for delivering notices across Telegram and Web Push channels. It emphasizes separation of concerns, dependency injection, and graceful degradation. Delivery guarantees are achieved by marking notices as sent only when at least one channel succeeds, while error handling and retry logic ensure resilience against transient failures. The design supports future extensions, such as additional channels or improved batching strategies, without disrupting existing functionality.